home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 1.iso / ARGONET / PD / MATHS / RLAB / RLAB125.ZIP / !RLaB / help_ai / getline < prev    next >
Text File  |  1995-05-15  |  4KB  |  108 lines
  1. getline:
  2.  
  3. Syntax:    getline ( FN )
  4.     getline ( FN, LL )
  5.  
  6. Description:
  7.  
  8.     Getline returns an N-element list which contains all of the
  9.     tokens from a line in the file described by FN. The tokens are
  10.     delimited by whitespace. Numbers are installed in the list as
  11.     numeric scalars, everything else is installed as scalar
  12.     strings.
  13.  
  14.     The list elements have numeric indices, and are numbered from
  15.     1 to N. The 1st element containing the 1st token on the line,
  16.     and the Nth element containing the last token on the line. The
  17.     newline is not returned as a token.
  18.  
  19.     Getline will also recognize everything enclosed within a pair
  20.     of `"' as a string, including escape characters.
  21.  
  22.     Getline will always return a list-object. When an empty-line
  23.     has been read, getline returns an empty list. Getline will
  24.     terminate on an End-Of-File (EOF).
  25.  
  26.     The filename can be a string that specifies a sub-process (see
  27.     `help FILES'), in which case getline() will run the
  28.     sub-process, and read from the process's standard output.
  29.  
  30.     The second, and optional argument, LL, forces getline to
  31.     return the entire line (including the newline) as a string,
  32.     without any parsing. If LL is <= 0, then getline will read
  33.     lines as long as 512 characters. If LL > 0, then getline will
  34.     read lines as long as LL characters. The return value is a
  35.     single string, not a list, when LL is used. If getline
  36.     encounters and EOF, while LL is being used, a numeric value of
  37.     0 is returned.
  38.  
  39.     Examples:
  40.  
  41.     To get input interactively:
  42.  
  43.     > printf( "Enter a string and a number: " ); x = getline( "stdin" );
  44.     Enter a string and a number: test-string 1.234e5
  45.     > show(x)
  46.        name:   x     
  47.        class:  list  
  48.            n:  2     
  49.     > x.[1]
  50.     test-string
  51.     > x.[2]
  52.      2 =
  53.      1.23e+05
  54.  
  55.     Given a file named `test', which contains the following lines:
  56.  
  57.     jcool  259  4 1075  822 vt01     S   Dec 29  9:32 X :0 -p 1 -s 5 
  58.     jcool  256  0   21    0 console  S   Dec 29  0:00 startx 
  59.     jcool  261  0  338   88 console  S   Dec 29  0:16 twm 
  60.     jcool  288  8  635  333 ?        S   Dec 29  2:00 emacs 
  61.     jcool  287  0  408   65 console  S   Dec 29  0:01 xclock 
  62.     
  63.     tmp = getline( "test" );
  64.     
  65.     would produce a list variable named `tmp' with 16 elements:
  66.     tmp.[1] would be the string "jcool" and tmp.[16] would be the
  67.     number 5.  The next call to getline() would read the second
  68.     line in the file, and create a new list containing those
  69.     elements.
  70.  
  71.     The above could also have been done with:
  72.  
  73.     tmp = getline( "|ps -aux | grep jcool" )
  74.  
  75.     Which would open a readable pipe to the "ps -aux | grep jcool"
  76.     command and grab a line at a time from the process.
  77.     
  78.     To read the entire contents of a file:
  79.  
  80.     if (length (ans = getline("stdin"))) 
  81.     { 
  82.       // do something with ans
  83.     else
  84.       // finish up
  85.         }
  86.  
  87.     Since getline returns an empty list when there is no input, we
  88.     can tell when to terminate the input loop by checking the
  89.     length of the returned list.
  90.  
  91.     Using the optional second arguemnt to getline we can get
  92.     old-style Fortran formattted output. For example, we have a
  93.     file filled with:
  94.  
  95. 0.1285186E+000.1463163E+000.0000000E+000.0000000E+000.0000000E+000.0000000E+00
  96. 0.0000000E+000.0000000E+000.0000000E+000.0000000E+000.7322469E-010.5245288E-01
  97. 0.0000000E+00-.9399651E-010.2397120E-01-.6551484E-010.2616772E+020.5796479E-01
  98. 0.0000000E+000.2500000E+000.7788281E-010.2121489E-010.0000000E+00-.1345507E+00
  99. 0.1516225E-01-.1284981E+000.1136876E+020.3010250E-010.0000000E+00-.2500000E+00
  100.  
  101.     we can do:
  102.  
  103.         lv = strtod (getline (FN, 13));
  104.  
  105.     and get a vector with the numeric values for each line.
  106.  
  107. See Also: FILES, LIST
  108.